home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / netzwerk / parnet / docs / parnet.doc < prev    next >
Text File  |  1996-02-26  |  9KB  |  201 lines
  1.  
  2.     NOTE TO DOUG:
  3.     Streams are not implemented yet.  The maximum packet size is 8K+256
  4.     bytes.    See iopar.c for example code.
  5.  
  6.     Note that the io requests (see parnet/devices/parnet.h) have a
  7.     secondary io_Data2 and io_Length2 field which allows you to write
  8.     from two buffers and read into two buffers... to prevent even more
  9.     buffer copying.  Be sure that said fields are NULL/0 when not used.
  10.  
  11.     AbortIO() works with CMD_READ requests for the datagram protocol.
  12.     The protocol and port must always be specified at OpenDevice() time,
  13.     while io_Addr (at least for datagrams) may be set on a per-io-request
  14.     basis.    I picked an arbitrary port for iopar.c ... a connection going
  15.     the other direction can be had by using a different port.
  16.  
  17.     Collision Warning:  DGRAMS are not reliable when collisions are
  18.     possible.  However, you will know when the write fails (io_Error will
  19.     return non-zero) so you *can* setup some code to retry if you wish.
  20.     This is pretty much required if you intend to allow cross-mounting
  21.     and stick with the DGRAM protocol.
  22.  
  23.     Eventually we may want to move to a STREAM protocol... once it gets
  24.     implemented.  But then again, datagrams are so efficient you might
  25.     not.  I dunno.    The CONNECT/LISTEN stuff applies only to the STREAM
  26.     protocol which has not been implemented yet.
  27.  
  28.                 -Matt
  29.  
  30.  
  31.                 PARNET.DEVICE DOC
  32.  
  33.                  GENERAL OVERVIEW
  34.  
  35.     The parnet.device driver works with one or MORE Amigas connected together
  36.     via a common, custom parallel port cable.  Refer to doc/Cable.DOC for
  37.     information on how to construct the cable.    Taking overhead into account
  38.     communication runs at about 23KBytes/sec (230KBaud).
  39.  
  40.     The limits of the network have not been determined yet, I have only been
  41.     able to test it with two Amiga's.  I am almost positive that it would
  42.     work with three or four Amigas assuming somebody takes the time to
  43.     construct the cableing.
  44.  
  45.     The network is based on machine addresses and rendezvous ports.  Each
  46.     machine on the network must have a unique address in the range 1-254.
  47.     0 and 255 are reserved.  This network has no broadcast capability.
  48.  
  49.     Multiple connections may exist between any two machines.  Each packet
  50.     contains a destination port number as well as a destination address.
  51.     Port numbers are unsigned words and may take on the value 0x0000 to
  52.     0x7FFF (0x8000-0xFFFF are reserved for stream connections).
  53.  
  54.     A number of protocols may be used:
  55.  
  56.     (1) Control Protocol, used for sending control commands to the
  57.         device rather than packets over the network.  Not really
  58.         a protocol.
  59.  
  60.     (2) DATA-GRAM Protocol, used for sending semi-reliable data between
  61.         machines.
  62.  
  63.     (3) STREAM Protocol, used for sending reliable data between machines.
  64.  
  65.  
  66.                 DATAGRAMS
  67.  
  68.     To use the datagram protocol you must specify the port number in the
  69.     OpenDevice() command.  Once you successfully open the device you may
  70.     issue CMD_READ and CMD_WRITE's to the device.  CMD_WRITE Iobs must
  71.     have a valid destination address in io_Addr.  You may modify this address
  72.     at any time before sending off the request.
  73.  
  74.     When a machine receives a datagram packet it copies it to the currently
  75.     pending CMD_READ request.  If you have not queued any CMD_READ requests
  76.     the packet is LOST.  The sending machine does not know whether a packet
  77.     it sends is thrown away or used.  I REPEAT, If there is no CMD_READ
  78.     request queued for a given port any packet sent to that port will be
  79.     lost!!!!
  80.  
  81.     Normally one uses datagrams to implement one's own high level stream
  82.     protocol.  Using datagrams has very low cost and, in fact, using
  83.     synchronous IO (DoIO()) will in many cases be able to send the packet
  84.     without doing a task switch.  Normally when one uses datagrams in this
  85.     manner one has several CMD_READ requests queued.  Never assume that
  86.     the receiving machine can keep up with the rate the sending machine
  87.     can send (this is normally fixed by having the sending machine wait for
  88.     an ack of some sort).
  89.  
  90.     Finally, blocking is maintained.  If the remote machine sends a 256 byte
  91.     packet and your pending CMD_READ can only handle 25, then only 25 bytes
  92.     will be copied and the rest thrown away.  If you CMD_READ can handle,
  93.     say, 300, then all 256 bytes will be copied.  The maximum packet size
  94.     is 4KBytes.
  95.  
  96.  
  97.                   STREAMS
  98.  
  99.     The Stream protocol provides the following services:
  100.  
  101.         - No loss of data
  102.         - Data is reliable
  103.         - No blocking factors
  104.         - Rate Control
  105.  
  106.     Openning a stream protocol connection is a two step process.  You must
  107.     specify a valid stream port in the OpenDevice() command.  OpenDevice()
  108.     will fill in the io_Unit field for that port.  The resulting Iob may
  109.     then be used to issue PPD_CONNECT and PPD_LISTEN commands.
  110.  
  111.     To connect to a remote machine copy the Iob to a new Iob (so the old
  112.     one is saved) and issue a PPD_CONNECT command using the new Iob.  The
  113.     stream protocol will arbitrate a connection with the remote machine
  114.     and then put that connection onto a dynamically determined port (in
  115.     the 0x8000-0xFFFF range), modifying the io_Unit field of the request
  116.     if the PPD_CONNECT is successful.  Further communication for that
  117.     connection must occur using the modified Iob.  That is, once a
  118.     connection is established further communication occurs on a different
  119.     port.
  120.  
  121.     You may still issue PPD_CONNECT and PPD_LISTEN commands on the original
  122.     Iob for the port.  Multiple tasks may open the same stream port but if
  123.     more than one task attempts a PPD_LISTEN then the task that actually
  124.     gets an incomming connection is indeterminant.
  125.  
  126.     To allow a remote machine to connect to a stream port you must issue a
  127.     PPD_LISTEN request in the same manner as the PPD_CONNECT request.
  128.     The PPD_LISTEN request waits for an incomming connection.  If you expect
  129.     to get several incomming connections at once you may want to issue
  130.     several PPD_LISTEN requests.  PPD_LISTEN returns when an incomming
  131.     connection is established and the io_Unit field is modified.  Further
  132.     communication for that connection must occur using the modified Iob.
  133.  
  134.     You may CloseDevice() the original io_Unit without having to
  135.     CloseDevice() connected units.  You MUST CloseDevice() a connected
  136.     unit when done with the connection.  That is, once a connection is
  137.     established it is independant of the original rendezvous port.
  138.  
  139.     Reading and Writing to a stream unit works somewhat like reading and
  140.     writing the serial port except that the data is reliably transmitted.
  141.     CMD_WRITE requests may block if the receiving machine's buffer is full.
  142.     CMD_READ requests block until at least 1 byte of data is available
  143.     then return immediately.  NO DATA IS LOST if new data comes in before
  144.     you can queue a CMD_READ request, and it is impossible for the sender
  145.     to overload the receiver.  You may also issue arbitrarily sized writes
  146.     but remember that all blocking factors are removed.  Issuing a 200 byte
  147.     write does not guarentee that all 200 bytes will be sent in the same
  148.     low level packet.
  149.  
  150.                 IO COMMANDS
  151.  
  152.  
  153.     PPD_SETADDR     This command sets our network address and may be sent
  154.             to any valid unit and always effects the entire device.
  155.  
  156.             Valid addresses range from 1 to 254.  This command may
  157.             be sent via any unit.
  158.  
  159.     PPD_SETTO        This command sets our network timeout and works like
  160.             PPD_SETADDR.. might be required when configuring with
  161.             faster processors due to timeout loops in the low level
  162.             packet send (the only way to make it go fast). This
  163.             command may be sent via any unit.
  164.  
  165.     PPD_SHUTDOWN    This command effects only connected STREAM units and
  166.             shutsdown one or both sides of the connection without
  167.             deallocating the unit structure.  It may be used to
  168.             send an EOF to other side, for example, or to inform
  169.             the other side that you are no longer receiving.
  170.  
  171.             Set io_Flags to:    0x01    no more reads
  172.                     0x02    no more writes (send EOF)
  173.                     0x03    both
  174.  
  175.     PPD_CONNECT     This command effects only unconnected STREAM units
  176.             (returned by OpenDevice) and allocates a port and
  177.             establishes a stream connection on it, returning the
  178.             new port and io_Unit if the connection is successful.
  179.  
  180.             Several PPD_CONNECT commands may be queued to the device
  181.             at once.
  182.  
  183.             On success, remember that the modified Iob is a completely
  184.             different Unit that must be CloseDevice()d to terminate.
  185.  
  186.     PPD_LISTEN        This command effects only unconnected STREAM units
  187.             as PPD_CONNECT and waits for a connection to be
  188.             established by a remote host, returning only when the
  189.             connection is established.    As in PPD_CONNECT a new
  190.             io_Unit is allocated for the connection.
  191.  
  192.             Several PPD_LISTEN commands may be queued to the device
  193.             at once and mixed with PPD_CONNECT commands (i.e. they
  194.             are independant).  Note that in some cases you want to
  195.             queue more than one in case several remote connect
  196.             requests occur at once.
  197.  
  198.             On success, remember that the modified Iob is a completely
  199.             different Unit that must be CloseDevice()d to terminate.
  200.  
  201.